// 版权所有2009 Go作者。版权所有。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package tar

import (
	"bytes"
	"io"
	"strconv"
	"strings"
	"time"
)

// 读卡器提供对tar存档内容的顺序访问。
// 读卡器。Next前进到归档文件中的下一个文件（包括第一个），
// 然后读卡器可以被视为io。读卡器来访问文件的数据。
type Reader struct {
	r    io.Reader
	pad  int64      // 当前文件项后的填充量（忽略）
	curr fileReader // 当前文件项的读取器
	blk  block      // 用作临时本地存储的缓冲区

	// 错误是一个持续性错误。
	// 只有每个导出的读卡器方法对
	// 负责确保此错误是粘性的。
	err error
}

type fileReader interface {
	io.Reader
	fileState

	WriteTo(io.Writer) (int64, error)
}

// NewReader创建一个从r读取的新读卡器。
func NewReader(r io.Reader) *Reader {
	return &Reader{r: r, curr: &regFileReader{r, 0}}
}

// Next前进到tar归档中的下一个条目。
// 标题。大小决定下一个文件可以读取多少字节。
// 当前文件中的任何剩余数据都将自动丢弃。
// 
// io。EOF在输入结束时返回。
func (tr *Reader) Next() (*Header, error) {
	if tr.err != nil {
		return nil, tr.err
	}
	hdr, err := tr.next()
	tr.err = err
	return hdr, err
}

func (tr *Reader) next() (*Header, error) {
	var paxHdrs map[string]string
	var gnuLongName, gnuLongLink string

	// 在外部，下一步将遍历tar归档文件，就像它是一系列
	// 文件一样。在内部，tar格式通常使用假“文件”来添加描述下一个文件的元数据
	// 数据。这些元数据“文件”通常不应该对外可见。同样地，这个循环在一个或多个“头文件”中迭代，直到找到一个“普通文件”。
	format := FormatUSTAR | FormatPAX | FormatGNU
	for {
		// 放弃文件的剩余部分和任何填充。
		if err := discard(tr.r, tr.curr.physicalRemaining()); err != nil {
			return nil, err
		}
		if _, err := tryReadFull(tr.r, tr.blk[:tr.pad]); err != nil {
			return nil, err
		}
		tr.pad = 0

		hdr, rawHdr, err := tr.readHeader()
		if err != nil {
			return nil, err
		}
		if err := tr.handleRegularFile(hdr); err != nil {
			return nil, err
		}
		format.mayOnlyBe(hdr.Format)

		// 检查PAX/GNU特殊的头文件和文件。
		switch hdr.Typeflag {
		case TypeXHeader, TypeXGlobalHeader:
			format.mayOnlyBe(FormatPAX)
			paxHdrs, err = parsePAX(tr)
			if err != nil {
				return nil, err
			}
			if hdr.Typeflag == TypeXGlobalHeader {
				mergePAX(hdr, paxHdrs)
				return &Header{
					Name:       hdr.Name,
					Typeflag:   hdr.Typeflag,
					Xattrs:     hdr.Xattrs,
					PAXRecords: hdr.PAXRecords,
					Format:     format,
				}, nil
			}
			continue // 这是一个影响下一个头的元头
		case TypeGNULongName, TypeGNULongLink:
			format.mayOnlyBe(FormatGNU)
			realname, err := io.ReadAll(tr)
			if err != nil {
				return nil, err
			}

			var p parser
			switch hdr.Typeflag {
			case TypeGNULongName:
				gnuLongName = p.parseString(realname)
			case TypeGNULongLink:
				gnuLongLink = p.parseString(realname)
			}
			continue // 这是一个影响下一个头的元头
		default:
			// 旧的GNU稀疏格式在这里处理，因为从技术上讲它是
			// 只是一个具有附加属性的常规文件。

			if err := mergePAX(hdr, paxHdrs); err != nil {
				return nil, err
			}
			if gnuLongName != "" {
				hdr.Name = gnuLongName
			}
			if gnuLongLink != "" {
				hdr.Linkname = gnuLongLink
			}
			if hdr.Typeflag == TypeRegA {
				if strings.HasSuffix(hdr.Name, "/") {
					hdr.Typeflag = TypeDir // 旧存档文件对目录使用尾随斜杠
				} else {
					hdr.Typeflag = TypeReg
				}
			}

			// 扩展头可能已经更新了大小。
			// 因此，在合并PAX头文件后，再次设置regFileReader。
			if err := tr.handleRegularFile(hdr); err != nil {
				return nil, err
			}

			// 稀疏格式依赖于能够读取逻辑数据
			// 节；必须在前面调用HandlerRegularFile。
			if err := tr.handleSparseFile(hdr, rawHdr); err != nil {
				return nil, err
			}

			// 设置格式的最终猜测。
			if format.has(FormatUSTAR) && format.has(FormatPAX) {
				format.mayOnlyBe(FormatUSTAR)
			}
			hdr.Format = format
			return hdr, nil // 这是一个文件，因此停止
		}
	}
}

// HandlerRegularFile设置当前文件读取器和填充，使其
// 只能读取以下逻辑数据部分。它将正确处理
// 不包含数据节的特殊头。
func (tr *Reader) handleRegularFile(hdr *Header) error {
	nb := hdr.Size
	if isHeaderOnlyType(hdr.Typeflag) {
		nb = 0
	}
	if nb < 0 {
		return ErrHeader
	}

	tr.pad = blockPadding(nb)
	tr.curr = &regFileReader{r: tr.r, nb: nb}
	return nil
}

// handleSparseFile检查当前文件是否为任何类型的稀疏格式
// 并适当设置当前读取器。
func (tr *Reader) handleSparseFile(hdr *Header, rawHdr *block) error {
	var spd sparseDatas
	var err error
	if hdr.Typeflag == TypeGNUSparse {
		spd, err = tr.readOldGNUSparseMap(hdr, rawHdr)
	} else {
		spd, err = tr.readGNUSparsePAXHeaders(hdr)
	}

	// 如果sp为非nil，则这是一个稀疏文件。
	// 注意len（sp）=0是可能的。
	if err == nil && spd != nil {
		if isHeaderOnlyType(hdr.Typeflag) || !validateSparseEntries(spd, hdr.Size) {
			return ErrHeader
		}
		sph := invertSparseEntries(spd, hdr.Size)
		tr.curr = &sparseFileReader{tr.curr, sph, 0}
	}
	return err
}

// readGNUSparsePAXHeaders检查PAX头中的GNU稀疏头。
// 如果找到了它们，那么这个函数将读取稀疏映射并返回它。
// 这假设0.0头已经被PAX头解析逻辑转换为0.1头
// 了。
func (tr *Reader) readGNUSparsePAXHeaders(hdr *Header) (sparseDatas, error) {
	// 标识GNU头的版本。
	var is1x0 bool
	major, minor := hdr.PAXRecords[paxGNUSparseMajor], hdr.PAXRecords[paxGNUSparseMinor]
	switch {
	case major == "0" && (minor == "0" || minor == "1"):
		is1x0 = false
	case major == "1" && minor == "0":
		is1x0 = true
	case major != "" || minor != "":
		return nil, nil // 未知GNU稀疏PAX版本
	case hdr.PAXRecords[paxGNUSparseMap] != "":
		is1x0 = false // 0.0和0.1没有明确的版本记录，所以猜测
	default:
		return nil, nil // 不是PAX格式的GNU稀疏文件。
	}
	hdr.Format.mayOnlyBe(FormatPAX)

	// 从GNU稀疏PAX头更新hdr。
	if name := hdr.PAXRecords[paxGNUSparseName]; name != "" {
		hdr.Name = name
	}
	size := hdr.PAXRecords[paxGNUSparseSize]
	if size == "" {
		size = hdr.PAXRecords[paxGNUSparseRealSize]
	}
	if size != "" {
		n, err := strconv.ParseInt(size, 10, 64)
		if err != nil {
			return nil, ErrHeader
		}
		hdr.Size = n
	}

	// 按照适当的格式阅读稀疏地图。
	if is1x0 {
		return readGNUSparseMap1x0(tr.curr)
	}
	return readGNUSparseMap0x1(hdr.PAXRecords)
}

// mergePAX将PaxHDR合并到标题所有相关字段的hdr中。
func mergePAX(hdr *Header, paxHdrs map[string]string) (err error) {
	for k, v := range paxHdrs {
		if v == "" {
			continue // 保留原始USTAR值
		}
		var id64 int64
		switch k {
		case paxPath:
			hdr.Name = v
		case paxLinkpath:
			hdr.Linkname = v
		case paxUname:
			hdr.Uname = v
		case paxGname:
			hdr.Gname = v
		case paxUid:
			id64, err = strconv.ParseInt(v, 10, 64)
			hdr.Uid = int(id64) // 可能存在整数溢出
		case paxGid:
			id64, err = strconv.ParseInt(v, 10, 64)
			hdr.Gid = int(id64) // 可能存在整数溢出
		case paxAtime:
			hdr.AccessTime, err = parsePAXTime(v)
		case paxMtime:
			hdr.ModTime, err = parsePAXTime(v)
		case paxCtime:
			hdr.ChangeTime, err = parsePAXTime(v)
		case paxSize:
			hdr.Size, err = strconv.ParseInt(v, 10, 64)
		default:
			if strings.HasPrefix(k, paxSchilyXattr) {
				if hdr.Xattrs == nil {
					hdr.Xattrs = make(map[string]string)
				}
				hdr.Xattrs[k[len(paxSchilyXattr):]] = v
			}
		}
		if err != nil {
			return ErrHeader
		}
	}
	hdr.PAXRecords = paxHdrs
	return nil
}

// parsePAX解析PAX标头。
// 如果扩展头（类型“x”）无效，则返回ErrHeader 
func parsePAX(r io.Reader) (map[string]string, error) {
	buf, err := io.ReadAll(r)
	if err != nil {
		return nil, err
	}
	sbuf := string(buf)

	// 以支持GNU PAX稀疏格式0.0。
	// 此函数将稀疏格式的0.0标头转换为格式0.1 
	// 标头，因为0.0标头不符合PAX。
	var sparseMap []string

	paxHdrs := make(map[string]string)
	for len(sbuf) > 0 {
		key, value, residual, err := parsePAXRecord(sbuf)
		if err != nil {
			return nil, ErrHeader
		}
		sbuf = residual

		switch key {
		case paxGNUSparseOffset, paxGNUSparseNumBytes:
			// 验证稀疏头顺序和值。
			if (len(sparseMap)%2 == 0 && key != paxGNUSparseOffset) ||
				(len(sparseMap)%2 == 1 && key != paxGNUSparseNumBytes) ||
				strings.Contains(value, ",") {
				return nil, ErrHeader
			}
			sparseMap = append(sparseMap, value)
		default:
			paxHdrs[key] = value
		}
	}
	if len(sparseMap) > 0 {
		paxHdrs[paxGNUSparseMap] = strings.Join(sparseMap, ",")
	}
	return paxHdrs, nil
}

// readHeader读取下一个块头，并假设基础读取器
// 已与块边界对齐。如果需要进一步处理，它将返回
// 头的原始块。
// 
// 错误将设置为io。只有当以下情况之一发生时，才会出现EOF：
// /*读取0个字节，并命中EOF。
// /*恰好读取1个零块，并命中EOF。
// /*至少读取2个零块。
func (tr *Reader) readHeader() (*Header, *block, error) {
	// 两个零字节块标志着存档的结束。
	if _, err := io.ReadFull(tr.r, tr.blk[:]); err != nil {
		return nil, nil, err // EOF在这里没问题；读取0字节
	}
	if bytes.Equal(tr.blk[:], zeroBlock[:]) {
		if _, err := io.ReadFull(tr.r, tr.blk[:]); err != nil {
			return nil, nil, err // EOF在这里没有问题；恰好1个零块读取
		}
		if bytes.Equal(tr.blk[:], zeroBlock[:]) {
			return nil, nil, io.EOF // 正常EOF；正好有两个零块读取
		}
		return nil, nil, ErrHeader // 零块，然后是非零块
	}

	// 验证标头是否与已知格式匹配。
	format := tr.blk.getFormat()
	if format == FormatUnknown {
		return nil, nil, ErrHeader
	}

	var p parser
	hdr := new(Header)

	// 解压缩V7头文件。
	v7 := tr.blk.toV7()
	hdr.Typeflag = v7.typeFlag()[0]
	hdr.Name = p.parseString(v7.name())
	hdr.Linkname = p.parseString(v7.linkName())
	hdr.Size = p.parseNumeric(v7.size())
	hdr.Mode = p.parseNumeric(v7.mode())
	hdr.Uid = int(p.parseNumeric(v7.uid()))
	hdr.Gid = int(p.parseNumeric(v7.gid()))
	hdr.ModTime = time.Unix(p.parseNumeric(v7.modTime()), 0)

	// 解压特定于格式的字段。
	if format > formatV7 {
		ustar := tr.blk.toUSTAR()
		hdr.Uname = p.parseString(ustar.userName())
		hdr.Gname = p.parseString(ustar.groupName())
		hdr.Devmajor = p.parseNumeric(ustar.devMajor())
		hdr.Devminor = p.parseNumeric(ustar.devMinor())

		var prefix string
		switch {
		case format.has(FormatUSTAR | FormatPAX):
			hdr.Format = format
			ustar := tr.blk.toUSTAR()
			prefix = p.parseString(ustar.prefix())

			// 对于格式检测，请检查块的格式是否正确，因为
			// 解析器比USTAR实际允许的更自由。
			notASCII := func(r rune) bool { return r >= 0x80 }
			if bytes.IndexFunc(tr.blk[:], notASCII) >= 0 {
				hdr.Format = FormatUnknown // 块中的非ASCII字符。
			}
			nul := func(b []byte) bool { return int(b[len(b)-1]) == 0 }
			if !(nul(v7.size()) && nul(v7.mode()) && nul(v7.uid()) && nul(v7.gid()) &&
				nul(v7.modTime()) && nul(ustar.devMajor()) && nul(ustar.devMinor())) {
				hdr.Format = FormatUnknown // 数值字段必须在Go1之前以NUL 
			}
		case format.has(formatSTAR):
			star := tr.blk.toSTAR()
			prefix = p.parseString(star.prefix())
			hdr.AccessTime = time.Unix(p.parseNumeric(star.accessTime()), 0)
			hdr.ChangeTime = time.Unix(p.parseNumeric(star.changeTime()), 0)
		case format.has(FormatGNU):
			hdr.Format = format
			var p2 parser
			gnu := tr.blk.toGNU()
			if b := gnu.accessTime(); b[0] != 0 {
				hdr.AccessTime = time.Unix(p2.parseNumeric(b), 0)
			}
			if b := gnu.changeTime(); b[0] != 0 {
				hdr.ChangeTime = time.Unix(p2.parseNumeric(b), 0)
			}

			// 结尾。8.编写器有一个错误，在某些罕见的情况下，它会输出一个无效的tar文件，因为逻辑
			// 错误地认为旧的GNU格式有一个前缀字段。
			// 这是错误的，会导致输出文件损坏
			// atime和ctime字段，这些字段通常未被使用。
			// 
			// 为了继续读取以前有缺陷的
			// 版本的Go创建的tar文件，我们怀疑地解析atime和ctime字段。
			// 如果我们无法解析它们，并且前缀字段看起来像
			// 一个ASCII字符串，那么我们可以使用前Go1。8行为
			// 将这些字段视为USTAR前缀字段。
			// 
			// 请注意，这不会对预Go1生成的所有可能的
			// 文件使用回退逻辑。8.工具链。如果生成的文件
			// 碰巧有一个前缀字段，解析为有效的
			// atime和ctime字段（例如，当它们是有效的八进制字符串时），
			// 则无法区分有效的GNU文件
			// 和无效的pre-Go1。8号文件。
			// 
			// 请参阅https:
			// 请参阅https:
			if p2.err != nil {
				hdr.AccessTime, hdr.ChangeTime = time.Time{}, time.Time{}
				ustar := tr.blk.toUSTAR()
				if s := p.parseString(ustar.prefix()); isASCII(s) {
					prefix = s
				}
				hdr.Format = FormatUnknown // 错误文件不是GNU 
			}
		}
		if len(prefix) > 0 {
			hdr.Name = prefix + "/" + hdr.Name
		}
	}
	return hdr, &tr.blk, p.err
}

// readOldGNUSparseMap从旧GNU稀疏格式读取稀疏映射。
// 如果稀疏映射足够小，它将存储在tar头中。
// 如果大于四个条目，则使用一个或多个扩展头来存储稀疏映射的其余部分。
// 
// 标题。大小不反映所使用的任何扩展头的大小。
// 因此，此函数将从原始io读取。读卡器获取额外的标题。
// 这个方法在这个过程中会变异blk。
func (tr *Reader) readOldGNUSparseMap(hdr *Header, blk *block) (sparseDatas, error) {
	// 确保输入格式为GNU。
	// 不幸的是，星型格式还有一个稀疏头格式，它使用
	// 相同的类型标志，但布局完全不同。
	if blk.getFormat() != FormatGNU {
		return nil, ErrHeader
	}
	hdr.Format.mayOnlyBe(FormatGNU)

	var p parser
	hdr.Size = p.parseNumeric(blk.toGNU().realSize())
	if p.err != nil {
		return nil, p.err
	}
	s := blk.toGNU().sparse()
	spd := make(sparseDatas, 0, s.maxEntries())
	for {
		for i := 0; i < s.maxEntries(); i++ {
			// 此终止条件与GNU和BSD tar相同。
			if s.entry(i).offset()[0] == 0x00 {
				break // 不返回，需要处理扩展头（即使是空的）
			}
			offset := p.parseNumeric(s.entry(i).offset())
			length := p.parseNumeric(s.entry(i).length())
			if p.err != nil {
				return nil, p.err
			}
			spd = append(spd, sparseEntry{Offset: offset, Length: length})
		}

		if s.isExtended()[0] > 0 {
			// 还有更多条目。读取扩展标题并解析其条目。
			if _, err := mustReadFull(tr.r, blk[:]); err != nil {
				return nil, err
			}
			s = blk.toSparse()
			continue
		}
		return spd, nil // Done 
	}
}

// readGNUSparseMap1x0读取以GNU的PAX稀疏格式存储的稀疏地图
// 1.0版。稀疏映射的格式由一系列
// 以换行符结尾的数字字段组成。第一个字段是条目数
// 并且始终存在。以下是条目，由两个
// 字段（偏移量、长度）组成。此函数必须在包含最后一个换行符的块边界的末尾
// 停止读取。
// 
// 请注意，GNU手册规定数值应以八进制
// 格式编码。然而，GNU tar实用程序本身以十进制形式输出这些值。
// 因此，该库将值视为十进制编码。
func readGNUSparseMap1x0(r io.Reader) (sparseDatas, error) {
	var (
		cntNewline int64
		buf        bytes.Buffer
		blk        block
	)

	// feedTokens将数据块中的数据从r复制到buf，直到buf中至少有cnt换行符。它不会读取超过需要的块。
	feedTokens := func(n int64) error {
		for cntNewline < n {
			if _, err := mustReadFull(r, blk[:]); err != nil {
				return err
			}
			buf.Write(blk[:])
			for _, c := range blk {
				if c == '\n' {
					cntNewline++
				}
			}
		}
		return nil
	}

	// nextToken获取由换行符分隔的下一个令牌。假设缓冲区中至少存在一个换行符。
	nextToken := func() string {
		cntNewline--
		tok, _ := buf.ReadString('\n')
		return strings.TrimRight(tok, "\n")
	}

	// 解析条目数。wen jian defg
	if err := feedTokens(1); err != nil {
		return nil, err
	}
	numEntries, err := strconv.ParseInt(nextToken(), 10, 0) // 有意将所有成员条目解析为原生int-
	if err != nil || numEntries < 0 || int(2*numEntries) < int(numEntries) {
		return nil, ErrHeader
	}

	// 解析。
	// 此后，numEntries是受信任的，因为潜在攻击者必须拥有与此库使用的资源成比例的
	// 已提交资源。
	if err := feedTokens(2 * numEntries); err != nil {
		return nil, err
	}
	spd := make(sparseDatas, 0, numEntries)
	for i := int64(0); i < numEntries; i++ {
		offset, err1 := strconv.ParseInt(nextToken(), 10, 64)
		length, err2 := strconv.ParseInt(nextToken(), 10, 64)
		if err1 != nil || err2 != nil {
			return nil, ErrHeader
		}
		spd = append(spd, sparseEntry{Offset: offset, Length: length})
	}
	return spd, nil
}

// readGNUSparseMap0x1读取以GNU的PAX稀疏格式
// 0.1版存储的稀疏地图。稀疏贴图存储在PAX标头中。
func readGNUSparseMap0x1(paxHdrs map[string]string) (sparseDatas, error) {
	// 获取条目数。
	// 使用整数防溢出数学来检查这一点。
	numEntriesStr := paxHdrs[paxGNUSparseNumBlocks]
	numEntries, err := strconv.ParseInt(numEntriesStr, 10, 0) // 有意将其解析为本机int-
	if err != nil || numEntries < 0 || int(2*numEntries) < int(numEntries) {
		return nil, ErrHeader
	}

	// 在sparseMap中，每个条目应该有两个数字。
	sparseMap := strings.Split(paxHdrs[paxGNUSparseMap], ",")
	if len(sparseMap) == 1 && sparseMap[0] == "" {
		sparseMap = sparseMap[:0]
	}
	if int64(len(sparseMap)) != 2*numEntries {
		return nil, ErrHeader
	}

	// 循环浏览稀疏映射中的条目。
	// 现在可以信任numEntries了。
	spd := make(sparseDatas, 0, numEntries)
	for len(sparseMap) >= 2 {
		offset, err1 := strconv.ParseInt(sparseMap[0], 10, 64)
		length, err2 := strconv.ParseInt(sparseMap[1], 10, 64)
		if err1 != nil || err2 != nil {
			return nil, ErrHeader
		}
		spd = append(spd, sparseEntry{Offset: offset, Length: length})
		sparseMap = sparseMap[2:]
	}
	return spd, nil
}

// 读取tar存档中的当前文件。
// 当它到达该文件的末尾时返回（0，io.EOF），
// 直到调用Next前进到下一个文件。
// 
// 如果当前文件是稀疏的，则标记为孔的区域
// 将作为NUL字节读回。
// 
// 在特殊类型上调用Read，如TypeLink、TypeSymlink、TypeChar、
// TypeBlock、TypeDir和TypeFifo返回（0，io.EOF），而不管头是什么。尺寸索赔。
func (tr *Reader) Read(b []byte) (int, error) {
	if tr.err != nil {
		return 0, tr.err
	}
	n, err := tr.curr.Read(b)
	if err != nil && err != io.EOF {
		tr.err = err
	}
	return n, err
}

// write将当前文件的内容写入w。
// 写入的字节数与当前文件中剩余的字节数匹配。
// 
// 如果当前文件是稀疏文件，并且w是io。WriteSeeker，
// 然后writeTo使用Seek跳过标题中定义的孔。SparseHoles，
// 假设跳过的区域填充了NUL。
// 这总是写入最后一个字节，以确保w的大小正确。
// 
// TODO（dsnet）：在添加稀疏文件支持时重新导出此文件。
// 参见https:
func (tr *Reader) writeTo(w io.Writer) (int64, error) {
	if tr.err != nil {
		return 0, tr.err
	}
	n, err := tr.curr.WriteTo(w)
	if err != nil {
		tr.err = err
	}
	return n, err
}

// regFileReader是一种文件读取器，用于从常规文件条目中读取数据。
type regFileReader struct {
	r  io.Reader // 基础读取器
	nb int64     // 要读取的剩余字节数
}

func (fr *regFileReader) Read(b []byte) (n int, err error) {
	if int64(len(b)) > fr.nb {
		b = b[:fr.nb]
	}
	if len(b) > 0 {
		n, err = fr.r.Read(b)
		fr.nb -= int64(n)
	}
	switch {
	case err == io.EOF && fr.nb > 0:
		return n, io.ErrUnexpectedEOF
	case err == nil && fr.nb == 0:
		return n, io.EOF
	default:
		return n, err
	}
}

func (fr *regFileReader) WriteTo(w io.Writer) (int64, error) {
	return io.Copy(w, struct{ io.Reader }{fr})
}

// 逻辑剩余实现文件状态。逻辑剩余。
func (fr regFileReader) logicalRemaining() int64 {
	return fr.nb
}

// 逻辑剩余实现文件状态。物理剩余。
func (fr regFileReader) physicalRemaining() int64 {
	return fr.nb
}

// sparseFileReader是一个文件阅读器，用于从稀疏文件条目中读取数据。
type sparseFileReader struct {
	fr  fileReader  // 底层文件读取器
	sp  sparseHoles // 稀疏孔的规范化列表
	pos int64       // 稀疏文件中的当前位置
}

func (sr *sparseFileReader) Read(b []byte) (n int, err error) {
	finished := int64(len(b)) >= sr.logicalRemaining()
	if finished {
		b = b[:sr.logicalRemaining()]
	}

	b0 := b
	endPos := sr.pos + int64(len(b))
	for endPos > sr.pos && err == nil {
		var nf int // 在片段
		holeStart, holeEnd := sr.sp[0].Offset, sr.sp[0].endOffset()
		if sr.pos < holeStart { // 在数据片段
			bf := b[:min(int64(len(b)), holeStart-sr.pos)]
			nf, err = tryReadFull(sr.fr, bf)
		} else { // 在孔片段
			bf := b[:min(int64(len(b)), holeEnd-sr.pos)]
			nf, err = tryReadFull(zeroReader{}, bf)
		}
		b = b[nf:]
		sr.pos += int64(nf)
		if sr.pos >= holeEnd && len(sr.sp) > 1 {
			sr.sp = sr.sp[1:] // 确保最后一个片段始终保持
		}
	}

	n = len(b0) - len(b)
	switch {
	case err == io.EOF:
		return n, errMissData // 密集文件中的数据比稀疏文件中的数据少
	case err != nil:
		return n, err
	case sr.logicalRemaining() == 0 && sr.physicalRemaining() > 0:
		return n, errUnrefData // 密集文件中的数据比稀疏文件中的数据多
	case finished:
		return n, io.EOF
	default:
		return n, nil
	}
}

func (sr *sparseFileReader) WriteTo(w io.Writer) (n int64, err error) {
	ws, ok := w.(io.WriteSeeker)
	if ok {
		if _, err := ws.Seek(0, io.SeekCurrent); err != nil {
			ok = false // 并非所有io。搜索者真的可以搜索
		}
	}
	if !ok {
		return io.Copy(w, struct{ io.Reader }{sr})
	}

	var writeLastByte bool
	pos0 := sr.pos
	for sr.logicalRemaining() > 0 && !writeLastByte && err == nil {
		var nf int64 // 片段大小
		holeStart, holeEnd := sr.sp[0].Offset, sr.sp[0].endOffset()
		if sr.pos < holeStart { // 在数据片段中
			nf = holeStart - sr.pos
			nf, err = io.CopyN(ws, sr.fr, nf)
		} else { // 在孔片段中
			nf = holeEnd - sr.pos
			if sr.physicalRemaining() == 0 {
				writeLastByte = true
				nf--
			}
			_, err = ws.Seek(nf, io.SeekCurrent)
		}
		sr.pos += nf
		if sr.pos >= holeEnd && len(sr.sp) > 1 {
			sr.sp = sr.sp[1:] // 确保最后一个片段始终保持
		}
	}

	// 如果最后一个片段是一个孔，那么在EOF之前搜索1字节，并且
	// 编写一个字节以确保文件大小正确。
	if writeLastByte && err == nil {
		_, err = ws.Write([]byte{0})
		sr.pos++
	}

	n = sr.pos - pos0
	switch {
	case err == io.EOF:
		return n, errMissData // 密集文件中的数据少于稀疏文件
	case err != nil:
		return n, err
	case sr.logicalRemaining() == 0 && sr.physicalRemaining() > 0:
		return n, errUnrefData // 密集文件中的数据多于稀疏文件
	default:
		return n, nil
	}
}

func (sr sparseFileReader) logicalRemaining() int64 {
	return sr.sp[len(sr.sp)-1].endOffset() - sr.pos
}
func (sr sparseFileReader) physicalRemaining() int64 {
	return sr.fr.physicalRemaining()
}

type zeroReader struct{}

func (zeroReader) Read(b []byte) (int, error) {
	for i := range b {
		b[i] = 0
	}
	return len(b), nil
}

// mustReadFull类似于io。ReadFull，但返回
// io。出人意料的错误。在读取len（b）字节之前命中EOF。
func mustReadFull(r io.Reader, b []byte) (int, error) {
	n, err := tryReadFull(r, b)
	if err == io.EOF {
		err = io.ErrUnexpectedEOF
	}
	return n, err
}

// tryReadFull就像io。ReadFull，但返回
// io。在读取len（b）字节之前命中时发生EOF。
func tryReadFull(r io.Reader, b []byte) (n int, err error) {
	for len(b) > n && err == nil {
		var nn int
		nn, err = r.Read(b[n:])
		n += nn
	}
	if len(b) == n && err == io.EOF {
		err = nil
	}
	return n, err
}

// 丢弃跳过r中的n个字节，如果无法这样做，则报告错误。
func discard(r io.Reader, n int64) error {
	// 如果可能，查找数据段末尾之前的最后一个字节。
	// 这样做是因为Seek通常懒于报告错误；这将掩盖
	// 流可能被截断的事实。我们可以依靠
	// io。CopyN很快完成，以触发任何IO错误。
	var seekSkipped int64 // 通过Seek跳过的字节数
	if sr, ok := r.(io.Seeker); ok && n > 1 {
		// 并非所有io。探索者实际上可以寻找。例如，操作系统。Stdin实现
		// io。Seek，但调用Seek总是返回错误并执行
		// 无操作。因此，我们尝试对当前的立场进行一次无辜的尝试，看看seek是否真的得到了支持。
		pos1, err := sr.Seek(0, io.SeekCurrent)
		if pos1 >= 0 && err == nil {
			// Seek似乎受支持，所以执行真正的Seek。
			pos2, err := sr.Seek(n-1, io.SeekCurrent)
			if pos2 < 0 || err != nil {
				return err
			}
			seekSkipped = pos2 - pos1
		}
	}

	copySkipped, err := io.CopyN(io.Discard, r, n-seekSkipped)
	if err == io.EOF && seekSkipped+copySkipped < n {
		err = io.ErrUnexpectedEOF
	}
	return err
}
